﻿<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<title>Stauffware.Essentials C# class library</title>
		<link href="../documentation/Stauffware.css" rel="StyleSheet" type="text/css" media="screen, print" />
	</head>
	<body>
		<div class="pageHdr" style="clear:both;">
			<table class="pageHdr"><tr class="pageHdr" valign="middle">
				<td class="crumb0"><a class="crumb0" href="..\_READ_ME_.html">Stauffware C#</a></td>
			</tr>
		</table>
		<table width="100%" cellspacing="0" cellpadding="0"><tr>
				<td align="center" width="19%"><a href="#Contents">Contents</a></td>
				<td align="center" width="19%"><a href="#Prerequisites">Prerequisites</a></td>
				<td align="center" width="19%"><a href="#HowToBuildIt">How to Build It</a></td>
				<td align="center" width="19%"><a href="#KnownIssues">Known Issues</a></td>
				<td align="center" width="19%"><a href="#RevisionHistory">Revision History</a></td>
		</tr></table>

		<a id="Contents" />
		<h2>Contents</h2>

		<h3>NiceXmlReader</h3>
		<p> This subclass of <code>System.Xml.XmlReader</code> wraps another<code>XmlReader</code>
			to provide the following additional capabilities:</p>
			<ul>
			<li>Optionally ignores the case of attribute names and element names.</li>
			<li>Optionally reports ignorable errors and continue processing.</li>
			<li>Detailed error reporting, including the location of the error 
				in the XML element tree, and (when available) the line number.</li>
			<li>Static methods for checking certain XML syntax rules.</li>
			<li>Typesafe <code>GetAttribute</code> methods for common data types (bool, int, float, etc.).</li>
			<li>Methods for easily reporting common XML errors.</li>
			<li>You can easily specify for each XML node type whether to ignore it, return it, 
				or throw an exception.</li>
			</ul>

		<h3>XmlError</h3>
		<p>This exception class has properties that report the line number, line position,
			and context in the element tree.</p>

		<h3>XmlUtils</h3>




		<h3>Xerialization (Xml Serialization)</h3>
		<p>A class library for adding XML serialization to other classes.  Its features include:</p>
			<ul>
			<li>Minimizes impact when adding serialization to existing classes.</li>
			<li>Reduces extra coding work through intelligent default behavior.</li>
			<li>Supports inheritence and generics.</li>
			<li>Allows the user (programmer) to specify whether class member values 
				get stored as XML attributes, XML elements, or XML text.</li>
			<li>Maintains the ordering of lists of objects serialized as XML child elements.</li>
			<li>On deserialization (reading XML), ignores the order of XML 
				attributes and sibling elements when the order doesn’t matter.</li>
			<li>Easy customization of [de]serialization behaviour when needed.</li>
			</ul>

			<p>See also <a href="documentation/XerializationTutorial.html">Xerialization Tutorial</a>.</p>
		
		<a id="Prerequisites" />
		<h2>Prerequisites</h2>
		
		<dl>
			<dt><b>Microsoft .Net Runtime</b> 4.0</dt>
			<dd></dd>
			<dt><b>Microsoft Visual Studio</b></dt>
			<dd>These libraries are maintained using a commercial (expensive)
				edition of Visual Studio.  They have also been successfully built using the
				free edition <a href="http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-csharp-express">Visual C# 2010 Express</a>.
				As of this writing, nobody has tried building them under 
				<a href="http://en.wikipedia.org/wiki/Mono_%28software%29">Mono</a>.
				</dd>
		</dl>

		<a id="HowToBuildIt" />
		<h2>How to Build It</h2>

			<ol>
				<li>Download and unpack (as needed) the sources into a directory of your choosing.</li>
				<li>Open Xml.sln using Microsoft Visual Studio.</li>
				<li>From the main menu bar, select "Build | Build Solution" or "Build | Rebuild Solution".</li>
			</ol>
		
		<a id="KnownIssues" />
		<h2>Known Issues</h2>

			<ul>
				<li>Need more and better unit tests.</li>
				<li>XmlMultiwriter is not ready.</li>
				<li>XmlUtils.ValidateXmlName doesn't check for "combining characters" or
					"extender characters".</li>
				<li>Consider adding support for concise (e.g. comma or space delimited)
					lists of scalars.</li>
				<li>Xerialization issues:
					<ul>
						<li>No proper support for multiple references to the same object.</li>
						<li>No explicit support for versioning.</li>
						<li>Tutorial is not finished.</li>
						<li>Given <code>class C1 { List&lt;C2&gt; L1; }</code>, Xerialization doesn't appear 
							to provide a way for the members of L1 to be direct XML child elements of C1,
							i.e. <code>&lt;C1&gt; &lt;C2/&gt; &lt;C2/&gt; &lt;C2/&gt; &lt;/C1&gt;</code>.
							</li>
					</ul>
				</li>
			</ul>

		
		<a id="RevisionHistory" />
		<h2>Revision History</h2>

			<dl>
				<dt><b>?? Aug 2014 - v.1.0</b></dt>
				<dd>No major changes, but it was really way past time to promote it to 1.0.
					<ul>
					<li>Fixed a bug where read-only fields were never being Xerialized.</li>
					<li>Refactored ad-hoc tests to Nunit unit tests.</li>
				</ul></dd>
				
				<dt><b>26 June 2014 - v.0.15</b></dt>
				<dd>(These changes were made in March, but didn't get checked in until June.)<ul>
					<li>Previous attempt to fix IgnoreXmlCase didn't work, and broke previously working code.
                        Implemented a new (and better) fix.</li>
					<li>Improved error handling.</li>
					<li>Minor doc changes.</li>
				</ul></dd>

				<dt><b>15 Dec 2013 - v.0.14</b></dt>
				<dd><ul>
					<li>CDATA wasn't being handled (on input).  Now it is.</li>
					<li>XerialContext.IgnoreXmlCase now works as advertised.</li>
					<li>Improved error handling with XerialException.</li>
				</ul></dd>

				<dt><b>2 August 2013 - v.0.13</b></dt>
				<dd><ul>
					<li>Improved error reporting, including line numbers.</li>
					<li>Re-implemented NiceXmlReader.LineNumber.</li>
					<li>Added "prebuilt" directory.</li>
				</ul></dd>

				<dt><b> - v.0.12</b></dt>
				<dd><ul>
					<li>Changed XerialContext.WriteToXml(object, XmlTextWriter)  
						to XerialContext.WriteToXml(object, XmlWriter).</li>
				</ul></dd>

				<dt><b> - v.0.11</b></dt>
				<dd><ul>
					<li>Bug fix.</li>
				</ul></dd>

				<dt><b> - v.0.10</b></dt>
				<dd><ul>
					<li>Improved error handling.</li>
				</ul></dd>

				<dt><b>21 March 2012 - v.0.9</b></dt>
				<dd><ul>
					<li>Added handling of classes derived from generic classes.  
						(risky; see Journal.doc)</li>
				</ul></dd>

				<dt><b>31 January 2012 - v.0.8</b></dt>
				<dd><ul>
					<li>improved documentation</li>
					<li>improved unit tests</li>
					<li>added handling for automatic backing fields in properties</li>
				</ul></dd>

				<dt><b>19 December 2011 - (no version change - BAD programmer!)</b></dt>
				<dd><ul>
					<li>Added built-in mappings for char, TimeSpan.</li>
					<li>Fixed crashing bug reading XML attributes.</li>
					<li>fixed XerialMemberAttribute.IsOptional</li>
					<li>improved documentation</li>
				</ul></dd>
					
				<dt><b>November 2011 - v.0.7</b></dt>
				<dd><ul>
					<li>Added Dump methods to TypeMappingDictionary, XerialTypeMapping, XerialMemberMapping.</li>
				</ul></dd>

				<dt><b>22 June 2011 - v.0.6</b></dt>
				<dd><ul>
					<li>modified TypeMappingDictionary.GetOrAdd to create mappings automatically</li>
					<li>improved determination of Inclusion and Encoding in XerialClassMapping</li>
					<li>added NullClassMapping to replace special handling of System.Object and System.ValueType;
						made some of XerialClassMapping's methods virtual</li>
					<li>made XerialTypeAttribute.MembersAreOptional nullable; added XerialContext.DefaultMemberOptionality</li>
					<li>added Enum_Extension_Methods (Enums.cs)</li>
					<li>added more XML comments to XerialContext</li>
				</ul></dd>

				<dt><b>21 June 2011 - v.0.5</b></dt>
				<dd></dd>
			</dl>

		<hr />
		<p style="font-size:90%">
			Copyright 2011 Edward L. Stauff.<br />
			Contact: <a href="mailto:EdStauff@gmail.com">EdStauff@gmail.com></a>
		</p>
		<div style="font-size:90%; border: 1px solid gray; margin: 1em 2em 1em 2em; padding: 0 1em 0 1em;">
			<p>
				This file is part of the "Stauffware.Xml" library.             
				"Stauffware.Essentials" is free software: you can redistribute it     
				and/or modify it under the terms of the GNU Lesser Public License as published     
				by the Free Software Foundation, either version 3 of the License, or (at your      
				option) any later version.                                                         
			</p><p>
				"Stauffware.Xml" is distributed in the hope that it will       
				be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of          
				MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser           
				Public License for more details.                                                   
			</p><p>
				You should have received a copy of the GNU Lesser Public License along with        
				"Stauffware.Xml".  If not, see 
				<a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>. 
			</p>
		</div>
	</body>
</html>

